<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Using Inkscape to create PolyAnim animations</title>
</head>
<body>
<span style=
"font-size: 120%; font-weight: bold;">InkscapeAnimationTutorial</span>
<div style="font-style: italic; margin-top: 3px;">Tutorial on how
to use Inkscape for creating PolyAnim animations</div>
<p>This tutorial was created on 13th July, 2008 by Mika Halttunen on the PolyAnim
wiki, and then copied to this HTML file. I do not plan to keep this file updated,
so be sure sure to check out the latest tutorial at <a href="http://code.google.com/p/polyanim/wiki/InkscapeAnimationTutorial">
http://code.google.com/p/polyanim/wiki/InkscapeAnimationTutorial</a>

<h1>Using Inkscape to create PolyAnim animations</h1>
<p>PolyAnim version 0.6 added an experimental / unsupported tool
that can convert specially made <a href="http://www.inkscape.org"
rel="nofollow">Inkscape</a> SVG files to PolyAnim XML animations.
This tutorial shows you how to create PolyAnim animations in
Inkscape. Mind you, it's not very pleasant nor flexible, but the
basic features work alright. :)</p>
<p>When I get the proper animation editor done, I'm hoping it will
make the creation of the animations easier.</p>
<h2>The first animation</h2>
<p>Download and install Inkscape from <a href=
"http://www.inkscape.org" rel=
"nofollow">http://www.inkscape.org</a>. This guide is tested with
Inkscape 0.46, but will most probably work for any version.</p>
<p>Let's start by creating a very simple animation. Start up
Inkscape and read on.</p>
<p><img src="pic01.png" /><br/><b>Picture 1.</b></p>
<p>See the marked top-left corner of the Inkscape document, as
shown in picture 1? Top-left is the origin for the final animation,
so you should design your animation around the top-left corner.
Yes, it's not very intuitive, but then again you don't really have
to think about it. :)</p>
<p>Let's create our first polygon. Note that the ConvertSVG tool
only supports the <strong>Path</strong> tool (Shift-F6) in
Inkscape. When you hover over the tool button, it shows <i>"Draw
Bezier curves and straight lines"</i>. Straight lines are what we
need to use. If you ever accidentally create curves, you need to
undo - <strong>the converter will not work with curved
lines</strong>.</p>
<p><img src="pic02.png" /><br/><b>Picture 2.</b></p>
<p>Select the Path-tool (marked in the picture 2), and draw a
diamond shape around the origin (the top-left corner) in
<strong>counter-clockwise order</strong>. For simplicity, you
should use counter-clockwise for each polygon you draw. The
direction itself doesn't matter, but it must be consistent across
the animation frames. So, click on the point marked
<strong>1.</strong>, then on <strong>2.</strong> and so forth.
Close the shape by clicking again on the first point
(<strong>1.</strong> / <strong>5.</strong>). Color the polygon as
you like (only simple color fill + opacity is supported, no
gradients unfortunately).</p>
<p><img src="pic03.png" /><br/><b>Picture 3.</b></p>
<p>In PolyAnim, all polygons must belong to a <strong>polygon
group</strong>. So, we need to wrap our lonely polygon into a group
in Inkscape. Yes, a group can consist of a single polygon as well
as many. ;) Click on the <i>Group selected objects</i> -button
marked in the picture 3. Right-click on the polygon, and select
<i>Object Properties</i> from the menu.</p>
<p><img src="pic04.png" /><br/><b>Picture 4.</b></p>
<p>A dialog shown in picture 4 will appear. You need to name the
polygon group by setting it's label. Type <strong>diamond</strong>
there and press <i>Set</i>. The actual label/name doesn't matter,
but it must be consistent through the animation frames.</p>
<p>At this point you should save your work (Ctrl-S). I've chosen to
save the document as <strong>diamond.svg</strong>. I've saved it to
my PolyAnim folder in my Eclipse workspace, so it'll be easily
accessible from the test program. But, before we can try that,
there's still a couple more things to do.</p>
<h3>How the key frames work</h3>
<p>Layers in Inkscape will be converted to PolyAnim key frames. The
frame transitition duration, which is the time in seconds it takes
to move from the previous frame to the current frame, is set by
renaming the layer in Inkscape. That was quite a mouthful, so let
us consider an example.</p>
<p>Suppose you have three frames of animation: A, B and C. A is the
first frame, B is the second and so forth. The frame transition
durations are: A = 0 secs, B = 1.5 secs and C = 1.0 secs. PolyAnim
will start from frame A, and proceed immediately (as the duration
is zero seconds) with a transition to frame B. That transition
takes exactly 1.5 seconds. Then, transition to frame C begins, and
it takes exactly 1.0 seconds. After that the animation is finished,
and it's total length is 0 + 1.5 + 1.0 = 2.5 seconds.</p>
<p><img src="pic05.png" /><br/><b>Picture 5.</b></p>
<p>So, select <i>Layer</i> --&gt; <i>Layers...</i> in Inkscape. The
layer view opens up to the right, as shown in picture 5. Click on
the text <i>"Layer 1"</i>, and rename it to <i>"1.0 secs"</i>
without the quotes. That gives the first frame a duration of 1.0
seconds, before PolyAnim starts the transition to the second frame.
The format for the layer names is: <strong>X.Y secs</strong> or
<strong>X.Y sec</strong> or <strong>X.Y s</strong> or
<strong>X.Y</strong> where <strong>X.Y</strong> is a floating point
number like <strong>1.0</strong> or <strong>0.75</strong>. The
seconds suffix is optional, and case-insensitive.
<strong>Note:</strong> Inkscape will not allow layers with the same
name, so if you need, say, more than one frame with the duration of
1.5 seconds, you need to get a little imaginative and use <i>1.5
s</i> for one frame, <i>1.5</i> for another, etc.</p>
<h3>Testing the converter</h3>
<p>Now we have a very simple animation, consisting of one static
diamond with the total duration of one seconds! Let's convert the
<strong>diamond.svg</strong> to <strong>diamond.xml</strong> and
try it in PolyAnim test program.</p>
<p>Assuming you've saved <strong>diamond.svg</strong> to your
PolyAnim workspace directory, you can use the following command
line to do the conversion:</p>
<pre class="prettyprint">
<span class="pln">java </span><span class=
"pun">-</span><span class="pln">cp bin nr</span><span class=
"pun">.</span><span class="pln">co</span><span class=
"pun">.</span><span class="pln">mhgames</span><span class=
"pun">.</span><span class="pln">polyanim</span><span class=
"pun">.</span><span class="pln">util</span><span class=
"pun">.</span><span class="typ">ConvertSVG</span><span class=
"pln"> diamond</span><span class="pun">.</span><span class=
"pln">svg diamond</span><span class="pun">.</span><span class=
"pln">xml</span>
</pre>
<p>If all goes well, ConvertSVG outputs</p>
<pre class="prettyprint">
<span class="typ">ConvertSVG</span><span class=
"pln"> </span><span class="pun">-</span><span class=
"pln"> unsupported </span><span class=
"typ">Inkscape</span><span class="pln"> SVG to </span><span class=
"typ">PolyAnim</span><span class=
"pln"> XML converter</span><span class="pun">.</span><span class=
"pln"><br /></span><span class=
"pun">-----------------------------------------------------------------</span>
<span class="pln"><br /></span><span class=
"typ">Parsing</span><span class="pln"> </span><span class=
"str">'diamond.svg'</span><span class="pun">..</span><span class=
"pln"> ok</span><span class="pun">.</span><span class=
"pln"><br /></span><span class="typ">Animation</span><span class=
"pln"> diamond</span><span class="pun">.</span><span class=
"pln">svg</span><span class="pun">:</span><span class=
"pln"> length </span><span class="lit">1.00s</span><span class=
"pun">,</span><span class="pln"> </span><span class=
"lit">1</span><span class="pln"> key frames</span><span class=
"pun">,</span><span class="pln"> nr</span><span class=
"pun">.</span><span class="pln">co</span><span class=
"pun">.</span><span class="pln">mhgames</span><span class=
"pun">.</span><span class="pln">polyanim</span><span class=
"pun">.</span><span class=
"pln">Animation@1201a25<br /><br /></span><span class=
"typ">Saving</span><span class=
"pln"> the animation to </span><span class=
"str">'diamond.xml'</span><span class="pun">..</span><span class=
"pln"> ok.</span>
</pre>
<p>You can then edit
<tt>nr.co.mhgames.polyanim.test.TestScene.java</tt> to display
<strong>diamond.xml</strong> instead of the Dude-animation. Find
the line</p>
<pre class="prettyprint">
<span class="pln">animation2 </span><span class=
"pun">=</span><span class="pln"> loader</span><span class=
"pun">.</span><span class="pln">readAnimation</span><span class=
"pun">(</span><span class="str">"dude.svg.xml"</span><span class=
"pun">);</span>
</pre>
<p>and replace <tt>dude.svg.xml</tt> with <tt>diamond.xml</tt>.
When we run either <strong>TestJava2D</strong> or
<strong>TestLWJGL</strong> we get something like in picture 6.</p>
<p><img src="pic06.png" /><br/><b>Picture 6.</b></p>
<p>Very neat, wouldn't you say? ;)</p>
<h3>Adding more frames</h3>
<p>All the awesomeness aside, a static animation ain't much of an
animation, right? We need more key frames.</p>
<p>Press the <i>Create a new layer</i> -button, marked green in
picture 5. Give the new layer a name <strong>1.5 secs</strong>.
That will make so the transition from frame #1 to #2 will take 1.5
seconds. Now we need to duplicate the layer 1 (frame 1) contents
into layer 2 (frame 2).</p>
<p>In the layers view, click on the first layer (named <i>1.0
secs</i>). Select <i>Edit</i> --&gt; <i>Select All</i> (Ctrl-A).
Then <i>Edit</i> --&gt; <i>Copy</i> (Ctrl-C). Now, select the new
layer (named <i>1.5 secs</i>) and <i>Edit</i> --&gt; <i>Paste In
Place</i> (Ctrl-Alt-V). After the groups have been copied, it's
usually wise to make sure the group names (labels) are stayed the
same. Remember, each group must have a consistent name in each
frame it appears in. So, right-click on the diamond, select
<i>Object properties</i> and make sure the label still reads
<i>diamond</i>.</p>
<p>Now, here's a little tip. From the layers view, select the first
layer/frame. Drag the opacity slider to something like 50% or
below. When you have more frames, I suggest you to hide all the
earlier frames except just the previous one. When the previous
frame is transparent, it's much easier to animate. Don't worry when
hidind/opacifying layers, they won't affect the resulting
animation.</p>
<p>Go back to the new layer/frame, by clicking on it. There's two
ways of animating in PolyAnim: you can animate the
<strong>groups</strong> as whole (by moving, scaling, rotating) or
animate the <strong>individual nodes (vertices)</strong> of the
group polygons. Here we're going to try both.</p>
<p>Select the diamond (make sure you're in layer named <strong>1.5
secs</strong>) and drag it up. You should have something like in
picture 7 now.</p>
<p><img src="pic07.png" /><br/><b>Picture 7.</b></p>
<p>Now we're going to manipulate the diamond vertices (<i>nodes</i>
in Inkscape). Select the <i>Edit paths by nodes</i> -tool (F2).
Move the left and right nodes as shown in picture 8.</p>
<p><img src="pic08.png" /><br/><b>Picture 8.</b></p>
<p>While we're at it, why not change the diamond color as well?
Having the adjusted diamond selected, assign it a new color. You
should save your work now (Ctrl-S), and run the conversion again.
If you check the PolyAnim test program, you should see the diamond
waiting 1.0 seconds and then moving updwards. It will also smoothly
change its color. Impressive, eh? ;)</p>

<p><img src="pic09.png" /><br/><b>Picture 9.</b></p>

<p>That concludes our very simple animation tutorial. :)
You can download the SVG created from here: <a href="diamond.svg">diamond.svg</a></p>
<p>Feel free
to inspect <strong>dude.svg</strong>, which is the Inkscape file
for the example animation (The Dude).</p>


<h2>Tips and caveats</h2>
<p>While working on more complex animations than the one described
above, you might run into some problems. Here a few common caveats
that you should keep in mind.</p>
<ul>
<li>The polygons render fine with Java2D but not in LWJGL!
Why?</li>
<li style="list-style: none">
<ul>
<li>You've used <a href=
"http://en.wikipedia.org/wiki/Convex_polygon" rel=
"nofollow">non-convex polygons</a>, which are not supported by
OpenGL and thus not by the PolyAnim LWJGL renderer. You need to
create more complex shapes in several convex parts. The Inkscape
grid mode might help to keep the polygon vertices aligned.</li>
</ul>
</li>
<li>PolyAnim crashes when rendering the animation</li>
<li style="list-style: none">
<ul>
<li>That is usually when the polygons of your groups do not match
between the frames. That is, in order for the animation to work,
polygon N in frame X must correspond to the polygon N in frame
Y.</li>
<li>In Inkscape, while you can change the depth order of groups
(with PageUp and PageDown keys), you cannot change the order of
group polygons.</li>
<li style="list-style: none">
<ul>
<li>If you need to change the order of polygons in a group, you
must make sure that the polygon order is the same for every frame
the group appears in.</li>
<li>Inkscapes XML editor might help you inspect the polygon order.
<i>Edit</i> --&gt; <i>XML Editor...</i></li>
</ul>
</li>
</ul>
</li>
<li>Shearing doesn't work as it should</li>
<li style="list-style: none">
<ul>
<li>Yep, it's not supported currently. Only scaling, translation
and rotation are.</li>
<li>Also note that Inkscape rotation is only between -180 and +180
degrees, while PolyAnim supports arbitary large rotations. These
will be supported in the upcoming animation editor. If you need to
make a group spin several times, you either need to make more key
frames with smaller rotations, or adjust the rotation by hand in
the converted XML file.</li>
</ul>
</li>
</ul>
<p><strong>Feel free to give comments, ask questions, etc.
:)</strong></p>

<p><a href="http://code.google.com/p/polyanim/wiki/InkscapeAnimationTutorial">
http://code.google.com/p/polyanim/wiki/InkscapeAnimationTutorial</a></p>

</body>
</html>
